Complimenting Code w/ Commenting

A few days ago I posted about mitigating complex code issues and introduced my opinion that commenting should be viewed as a last resort.That post kicked up some discussion on Facebook with some of my friends:“Documentation and commenting is still important”-Close friend from college“I think it can be important, but I would much rather see time invested in writing better code and hiring more talented developers."-Former co-worker in response to above commentOf course I never meant to imply that code commenting isn’t important. But I do believe that efforts should first be made to improve code quality, and then use commenting to compliment code that is either too complex or sophisticated to clean up.So what does documentation/commenting mean to me?Documentation does NOT mean a single line telling the developer what this line does. That might be necessary for larger methods with many lines of code, but for a short and/or complex group of code such as this, you need to document HOW this line works.Below is a comment I consider good for the code in my previous post:# Perl.pl excerpt### Use smart match operator to compare values in hash to Regex# Grep to capture all keys from successful smart matches.my @matches = grep {$$hash{$_} ~~ /($target)/} keys %$hash;Note in the first line I make an explicit reference to “smart match”. This gives the more junior developer something to google if they’ve never seen the ~~ operator before.Next, I reference the smart matching subcomponent in the wrapping functionality, which is a somewhat basic grep search.sourceDocumentation also does NOT mean writing a book. If you find yourself writing 10 lines of code comments to explain something, you’ll often find that in addition to no one actually reading the comments, you probably don’t truly understand the code yourself. Unless your goal is purely job security, it’s your duty as a good engineer to leverage the KISS Principle (Keep It Simple, Stupid) and make life easier for other engineers.Besides, it’s also a way to double check yourself. As Einstein once said:     “If you can’t explain it simply, you don’t understand it well enough."All too often I see developers implement code that “works” without a truly deep understanding of what they actually did and the implications of it. That’s a recipe for bugs and side effects.You also don’t want to handhold the more junior developer here either. There are some things you just have to assume they are smart enough to understand. (Like the hash reference %$ in the code above)It’s really:When you combine common components (grep, regex, hash reference, smart match) into complex functionality that is not often seen in your code base or other projects, you need to comment.Often, I’ll bet that if you follow some of this philosophy, your future self will thank you as he/she will likely be the first one to have to fix some confusing code you left behind.